-
Notifications
You must be signed in to change notification settings - Fork 37.7k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Link alternate documentation formats #27015
Conversation
Link the HTML to the PDF and vice-versa.
Thanks for the PR! I'm noticing that more than half the page is taken up by logos, titles, and links to other resources. This is what it looks like in my browser: I realize that most of it is unrelated to this change, but nevertheless it seems a good opportunity to bring this up and see how we can optimize it so that the main content with the links does not require scrolling. |
We lose a lot of space in the border around the version (especially) and around the wiki link (though less so). The border around the note for other formats could be thinner, too. Also, other projects put the content that Spring Framework is keeping in the wiki into a section within the docs (so in a link within the list of links). Aside from this layout issue, another concern I have is that readers who are familiar with our other docs won't think to look for a wiki link (even though it is called out at the top - people do get into ruts). Consider Spring Boot's layout (https://docs.spring.io/spring-boot/docs/current/reference/html/). The spacing seems much more friendly, because it is considerably tighter and gets more content into the same space. (Note that I would move the author list to the bottom, because very few readers are looking for it.) Could Framework adopt Boot's styling? Boot has a backend project that Framework could use (and that I hope all Spring projects will eventually use). Similarly, can we move the content in the wiki into a topic within the regular contents list? |
Thanks for the feedback and pointers. For the use of the wiki, at some point we moved all cross-version information there. This is quite intentional as it allows us to target multiple generations and versions from one place and it allows us to continuously make updates. I've made some additional updates. The link to the wiki is now folded into the main index of links at the end. I've also moved the link to the PDF links below the main index. I don't think it needs to be the first thing to see unless we can fine a more compact way to display it. For the version, we're looking for a way to display it in a less obtrusive way. It's controlled by the revision line property of Asciidoctor and it doesn't seem easy to customize but we might be able to target it very specifically with the style for Adopting Boot's backend and resulting HTML/CSS would also help but until then we can try to update our current CSS. |
We ended up taking a different approach as outlined in the commit message for 71995a9. The upcoming snapshot docs should therefore look like the following. |
Link the HTML to the PDF and vice-versa.